Scriptname: dsFilename.au3

Author:	Dark$oul71

Contact: darksoul71@gmx.de

Purpose:	
Filename.au3 is a small set of UDFs (=User defined functions) which
I developed for my own little scripts. Freel free to use the source
code as you like. I just would like to encourage everyone to release
his sources under GPL whenever you distribute a script as binary.
My UDFs are depending on the file.au3 script from the latest beta
as Im using some of the included functions.

Functions included and what the do:

*Func _FileExtractPath ($FileName)
This function extracts the file path with trailing "\" for a 
filename with path. 

Example: _FileExtractPath("C:\MyPath\MyFile.TXT") returns "C:\MyPath\"


* Func _FileExtractFilename ($FileName)
This function extracts the file name for a filename with path. 

Example: _FileExtractFilename("C:\MyPath\MyFile.TXT") returns "MyFile.TXT"


* Func _FileGetExt ($FileName)
This function returns the extension for a filename with path with "."

Example: _FileGetExt ("C:\MyPath\MyFile.TXT") returns ".TXT"


* Func _FileChangeExt ($FileName, $Extension)
This function changes the extension for a filename with path.

Example: _FileChangeExt ("C:\MyPath\MyFile.TXT", "doc") returns "C:\MyPath\MyFile.doc"

* Func _FileStripExt ($FileName)
This function strips the extension for a filename with path.

Example: _FileStripExt ("C:\MyPath\MyFile.TXT") returns "C:\MyPath\MyFile"


* Func _FileIncrementFileName ($FileName)
This function generates a unique filename for a filename with path if the file exists.

Example: _FileIncrementFileName ("C:\MyPath\MyFile.TXT") returns
	"C:\MyPath\MyFile.TXT"     when "C:\MyPath\MyFile.TXT"     does not exist
	"C:\MyPath\MyFile (1).TXT" when "C:\MyPath\MyFile.TXT"     does exist
	"C:\MyPath\MyFile (2).TXT" when "C:\MyPath\MyFile (1).TXT" does exist
	"C:\MyPath\MyFile (3).TXT" when "C:\MyPath\MyFile (2).TXT" does exist
	and so on.

Ive provided a little sample script called "MoveFileUnique.au3" as example for what you
can use this function.

* Func _GenerateIncrementedFileNames ($FullPath, $Count, byRef $myArray)

This function is intended to be a "counterpart" for _FileIncrementFileName and generates
a directory which keeps up to $Count filenames with the same naming scheme as _FileIncrementFileName
produces. This enables you to search for incremental filnames based on the "base name" without dealing
with FileFindFirstFile. In one of my scripts I use _FileIncrementFileName to store multiple setting files
under unique names. Afterwards I generate an array with _GenerateIncrementedFileNames with 10000 filenames
and do a simple "FileExists" loop for each of those filenames stored in the array.

Note: If $myArray isnt initialized, the function will do a DIM by itself. 

Example: _GenerateIncrementedFileNames ("C:\MyPath\MyFile.TXT", 4, $myArr) would return the following array
$myArr[0] = "C:\MyPath\MyFile.TXT"    
$myArr[1] = "C:\MyPath\MyFile (1).TXT"
$myArr[2] = "C:\MyPath\MyFile (2).TXT"
$myArr[3] = "C:\MyPath\MyFile (3).TXT"

* Func _DrivePercentFree ($FullPath)
This function return the available diskspace on a drive in %

Example: _DrivePercentFree ("C:\") would return 50 if your HD has a size of 8 GB and 4 GB are still free.

* Func _IsSearchedType ($FullPath, $Types)
This function return "1" it the filename in $FullPath matches one of the extension defined by $Types
and returns "0" if it doesnt match any of the defined extensions. $Types can be a single extension without 
any separator (e.g. $Types = "txt") or multiple extensions using one of the following separators "|,;:",
e.g. $Types = "avi,mpg,mpeg" is similar to $Types = "avi|mpg|mpeg" or $Types = "avi:mpg:mpeg" 
The dot for the extension is optional and will be added if missing, e.g. both $Types = ".avi,.mpg" and
$Types = "avi,mpg" are valid. Extensions are NOT casesensitive and will be converted to uppercase prior 
comparison.

Example: _IsSearchedType ("C:\This is a file.txt", "txt,doc,rtf") would return 1 as one of the specified
extensions is txt.  

* Func _FileSearchForText ($SearchFile, $SearchString, $CaseSensitive)
This function searches for a searchstring within a textfile. The search can be casesensitive or
not. 

Example: 
_FileSearchForText ("C:\myTextfile.txt", "myString", 1) returns 1 if "myString" is found within 
"C:\myTextfile.txt" or returns 0 if its not found. Setting $CaseSensitive to 0 will deactivate
casesensitive search. In other words "myString" equals "MYSTRING", "mySTRING", MyStRiNG", etc.

* Func _FileSearchAndReplaceText ($SearchFile, $SearchString, $ReplaceString, $CaseSensitive)
This function does nearly the same as _FileSearchForText but instead of only searching for a 
searchstring within a textfile, it will replace any instance of the found string by $ReplaceString. 
The search and replace process can be casesensitive or not. 

Examples: 
_FileSearchAndReplaceText ("C:\myTextfile.txt", "myString", "Replace", 1) will replace any instance
of "myString" within "C:\myTextfile.txt" by the String "Replace". Setting $CaseSensitive to 0 will 
deactivate casesensitive search and replace. In other words "myString" equals "MYSTRING", "mySTRING", 
MyStRiNG", etc. and will be replaced by the String "Replace".

* Func _FileAppendTextfile ($ToAppend, $FromAppend)
This function appends the content of the textfile specified under $FromAppend to the textfile specified
under $ToAppend.

Example:
_FileAppendTextfile ("C:\myFile.txt", "C:\myAppendFile.txt") would append all the content from
"C:\myAppendFile.txt" at the end of "C:\myFile.txt". 


Final words:
Feel free to contact me if you have any questions or ideas on this script. Mind you that
I release those scripts without any warranty, e.g. if you use those function within your
backup script and loose your original data because of a bug within _FileIncrementFileName
Im not responsible for this.

No animals or developers were hurt during the generation of this code <ggg>

Later,
D$
